package cn.iocoder.yudao.module.system.service.exam;

import cn.iocoder.yudao.module.system.controller.admin.exam.vo.*;
import cn.iocoder.yudao.module.system.dal.dataobject.exam.*;

import java.util.List;

/**
 * 测评数据存储 Service 接口
 *
 * @author 芋道源码
 */
public interface ExamDataService {

    // ========== 题目相关 ==========

    /**
     * 保存测评题目数据
     *
     * @param appKey API密钥
     * @param tbl 测评类型标记值
     * @param questions 题目列表
     */
    void saveQuestions(String appKey, String tbl, List<ExamTestQuestionVO> questions);

    /**
     * 获取测评题目数据
     *
     * @param tbl 测评类型标记值
     * @return 题目列表
     */
    List<ExamTestQuestionVO> getQuestions(String tbl);

    /**
     * 根据第三方API题目ID获取题目
     *
     * @param apiDetailsId 第三方API题目ID
     * @return 题目信息
     */
    ExamQuestionDO getQuestionByApiDetailsId(Long apiDetailsId);

    /**
     * 根据第三方API题目ID和测评类型获取题目（更精确的查询）
     *
     * @param apiDetailsId 第三方API题目ID
     * @param tbl 测评类型标记值
     * @return 题目信息
     */
    ExamQuestionDO getQuestionByApiDetailsIdAndTbl(Long apiDetailsId, String tbl);

    // ========== 测评信息相关 ==========

    /**
     * 保存测评信息数据
     *
     * @param appKey API密钥
     * @param tbl 测评类型标记值
     * @param testInfo 测评信息
     */
    void saveTestInfo(String appKey, String tbl, ExamTestInfoVO testInfo);

    /**
     * 获取测评信息数据
     *
     * @param tbl 测评类型标记值
     * @return 测评信息
     */
    ExamTestInfoVO getTestInfo(String tbl);

    // ========== 测评报告相关 ==========

    /**
     * 保存测评报告数据
     *
     * @param userId 用户ID
     * @param appKey API密钥
     * @param tbl 测评类型标记值
     * @param testBatchNo 测试批次号
     * @param submitReqVO 提交的答案
     * @param report 测评报告
     */
    void saveTestReport(Long userId, String appKey, String tbl, String testBatchNo, 
                       ExamAnswerSubmitReqVO submitReqVO, ExamTestReportVO report);

    /**
     * 获取测评报告数据
     *
     * @param userId 用户ID
     * @param testBatchNo 测试批次号
     * @return 测评报告
     */
    ExamTestReportVO getTestReport(Long userId, String testBatchNo);

    /**
     * 获取用户最新的测评报告
     *
     * @param userId 用户ID
     * @return 最新的测评报告
     */
    ExamTestReportVO getLatestTestReport(Long userId);

    /**
     * 获取用户测评历史
     *
     * @param userId 用户ID
     * @return 测评历史列表
     */
    List<ExamTestReportVO> getUserTestHistory(Long userId);

    /**
     * 根据答题组合查询已缓存的报告
     *
     * @param appKey API密钥
     * @param tbl 测评类型标记值
     * @param reportType 报告类型
     * @param answerString 答案字符串
     * @param isAllAnswer 是否提交所有题目的答案
     * @return 已缓存的测评报告，如果没有则返回null
     */
    ExamTestReportVO getCachedTestReport(String appKey, String tbl, String reportType,
                                        String answerString, String isAllAnswer);

    // ========== 答题记录相关 ==========

    /**
     * 保存用户答题记录
     *
     * @param userId 用户ID
     * @param testBatchNo 测试批次号
     * @param submitReqVO 提交的答案
     */
    void saveUserAnswers(Long userId, String testBatchNo, ExamAnswerSubmitReqVO submitReqVO);

    /**
     * 获取用户答题记录
     *
     * @param userId 用户ID
     * @param testBatchNo 测试批次号
     * @return 答题记录列表
     */
    List<ExamUserAnswerDO> getUserAnswers(Long userId, String testBatchNo);

    // ========== 数据清理相关 ==========

    /**
     * 清理过期数据
     *
     * @param tbl 测评类型标记值
     */
    void cleanExpiredData(String tbl);

    /**
     * 删除用户测评记录
     *
     * @param userId 用户ID
     * @param testBatchNo 测试批次号
     */
    void deleteUserTestRecord(Long userId, String testBatchNo);

}
